fix(nextjs): add runtime error for auth() misimport from main entry point by alexcarpenter · Pull Request #8487 · clerk/javascript

alexcarpenter · 2026-05-06T14:50:10Z

Summary

When importing auth from @clerk/nextjs instead of @clerk/nextjs/server, the bundler previously showed a generic 'auth' is not exported from '@clerk/nextjs' error with no hint about the correct import path
Replaces the type-only declare const auth: never stub with a real runtime Proxy that throws a descriptive error: Clerk: auth() was imported from '@clerk/nextjs'. The auth() helper is a server-side function and must be imported from '@clerk/nextjs/server'.
The Proxy catches both function calls (auth()) and property access (auth.protect), so the helpful error surfaces regardless of how the developer uses the misimported binding

BEFORE	AFTER

Ref: SDK-65

Test plan

Added auth-misimport.test.ts covering both function call and property access scenarios
Existing server exports snapshot test still passes
Verify in a Next.js app that import { auth } from '@clerk/nextjs' shows the new error instead of the bundler error

🤖 Generated with Claude Code

…oint When developers import `auth` from `@clerk/nextjs` instead of `@clerk/nextjs/server`, the bundler shows a generic "'auth' is not exported" error with no guidance. Replace the type-only `declare const` stub with a real runtime Proxy export that throws a clear error message pointing to the correct import path. Ref: SDK-65 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

vercel · 2026-05-06T14:50:16Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	May 7, 2026 0:17am

changeset-bot · 2026-05-06T14:50:21Z

🦋 Changeset detected

Latest commit: 140d334

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@clerk/nextjs	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

coderabbitai · 2026-05-06T14:53:09Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 333a0fe2-850b-4262-96b9-711535d43451

📥 Commits

Reviewing files that changed from the base of the PR and between 7e031ec and 140d334.

📒 Files selected for processing (2)

.changeset/auth-misimport-runtime-error.md
packages/nextjs/src/index.ts

✅ Files skipped from review due to trivial changes (1)

.changeset/auth-misimport-runtime-error.md

🚧 Files skipped from review as they are similar to previous changes (1)

packages/nextjs/src/index.ts

📝 Walkthrough

Walkthrough

This PR adds a deprecation notice to the auth export in packages/nextjs/src/index.ts to guide developers toward the correct import path (@clerk/nextjs/server). The deprecation is communicated via an updated JSDoc comment that will appear in IDE tooltips. A corresponding changeset file documents this patch release and explains the improved developer experience.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly and accurately describes the main change: adding a runtime error for auth() misimport from the main entry point, which is the primary objective of the PR.
Description check	✅ Passed	The description is well-related to the changeset, explaining the problem (generic bundler error), the solution (runtime Proxy with descriptive error), and providing context with before/after screenshots.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

alexcarpenter · 2026-05-06T14:53:27Z

!snapshot

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

pkg-pr-new · 2026-05-06T14:59:26Z

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8487

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8487

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8487

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8487

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@8487

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8487

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8487

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8487

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8487

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8487

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8487

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8487

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8487

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8487

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8487

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8487

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8487

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8487

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8487

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8487

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8487

commit: 140d334

Ephem · 2026-05-07T07:26:17Z

 * API Routes, Server Components, Server Actions, and Middleware.
 */
-export declare const auth: never;
+export { auth } from './server-only-stubs';


Does this approach move the error from being a build time one to being a runtime one? I'm not sure we should do that, I'd rather take a less specific error at build time than a great one at runtime or else users risk deploying bugs to production before catching the error?

I didn't think much about feasibility or where the current message was coming from when I wrote the issue. :/

yeah, I agree the tradeoff probably isn't worth it. losing the build-time check to improve a runtime error risks letting misimports ship to production for that subset of users.

wdyt about adding a @deprecated jsdoc notice? 140d334

github-actions Bot added the nextjs label May 6, 2026

chore: add changeset for auth misimport error

7e031ec

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

vercel Bot deployed to Preview May 6, 2026 14:55 View deployment

Ephem reviewed May 7, 2026

View reviewed changes

change approach to jsdoc @deprecated notice

140d334

vercel Bot deployed to Preview May 7, 2026 12:17 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(nextjs): add runtime error for auth() misimport from main entry point#8487

fix(nextjs): add runtime error for auth() misimport from main entry point#8487
alexcarpenter wants to merge 3 commits intomainfrom
alex/sdk-65-auth-misimport-error

alexcarpenter commented May 6, 2026 •

edited

Loading

Uh oh!

vercel Bot commented May 6, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented May 6, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented May 6, 2026 •

edited

Loading

Walkthrough

Estimated code review effort

Uh oh!

alexcarpenter commented May 6, 2026

Uh oh!

pkg-pr-new Bot commented May 6, 2026 •

edited

Loading

Uh oh!

Ephem May 7, 2026 •

edited

Loading

Uh oh!

alexcarpenter May 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

alexcarpenter commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

vercel Bot commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

coderabbitai Bot commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Estimated code review effort

Uh oh!

alexcarpenter commented May 6, 2026

Uh oh!

pkg-pr-new Bot commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Ephem May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexcarpenter May 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

alexcarpenter commented May 6, 2026 •

edited

Loading

vercel Bot commented May 6, 2026 •

edited

Loading

changeset-bot Bot commented May 6, 2026 •

edited

Loading

coderabbitai Bot commented May 6, 2026 •

edited

Loading

pkg-pr-new Bot commented May 6, 2026 •

edited

Loading

Ephem May 7, 2026 •

edited

Loading